<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">

<HTML>
  <HEAD>
    <TITLE>PyGhidra Interpreter</TITLE>
    <LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
  </HEAD>

  <BODY lang="EN-US">
    <H1><A name="PyGhidra"></A>PyGhidra Interpreter</H1>

    <P>
    The Ghidra <I>PyGhidra Interpreter</I> provides a full general-purpose Python interactive shell
    and allows you to interact with your current Ghidra session by exposing Ghidra's powerful Java 
    API through the magic of Jpype. 
    </P>

    <H2>Environment</H2>
    <BLOCKQUOTE>
    <P>
    The Ghidra <I>PyGhidra Interpreter</I> is configured to run in a similar context as a Ghidra
    script.  Therefore, you immediately have access to variables such as <TT>currentProgram</TT>, 
    <TT>currentSelection</TT>, <TT>currentAddress</TT>, etc without needing to import them.  
    These variables exist as Java objects behind the scenes, but Jpype allows you to interact with 
    them through a Python interface, which is similar to Java in some ways.
    </P>
    
    <P>
    As in Java, classes outside of your current package/module need to be explicitly imported.
    For example, consider the following code snippet:
    </P>
    <BR>
    
    <PRE>
    <FONT COLOR="GREEN"># Get a data type from the user</FONT>
    tool = state.getTool()
    dtm = currentProgram.getDataTypeManager()
    from ghidra.app.util.datatype import DataTypeSelectionDialog
    from ghidra.util.data.DataTypeParser import AllowedDataTypes
    selectionDialog = DataTypeSelectionDialog(tool, dtm, -1, AllowedDataTypes.FIXED_LENGTH)
    tool.showDialog(selectionDialog)
    dataType = selectionDialog.getUserChosenDataType()
    if dataType != None: print("Chosen data type: " + str(dataType))
    </PRE>
    
    <P>
    <TT>currentProgram</TT> and <TT>state</TT> are defined within the Ghidra scripting class 
    hierarchy, so nothing has to be explicitly imported before they can be used.  However, because 
    the <TT>DataTypeSelectionDialog</TT> class and <TT>AllowedDataType</TT> enum reside in  
    different packages, they must be explicitly imported. Failure to do so will result in a 
    Python <TT><FONT COLOR="RED">NameError</FONT></TT>.
    </P>
    </BLOCKQUOTE>
    
    <H2><A name="Clear_Interpreter"></A>Clear <IMG border="0" src="images/erase16.png"></H2>
    <BLOCKQUOTE>
    <P>
    This command clears the interpreter's display.  Its effect is purely visual.
    It does not affect the state of the interpreter in any way.
    </P>
    </BLOCKQUOTE>

    <H2><A name="Interrupt_Interpreter"></A>Interrupt <IMG border="0" src="images/dialog-cancel.png"></H2>
    <BLOCKQUOTE>
    <P>
    This command issues a keyboard interrupt to the interpreter, which can be used to interrupt
    long running commands or loops.
    </P>
    </BLOCKQUOTE>
    
    <H2><A name="Reset_Interpreter"></A>Reset <IMG border="0" src="images/reload3.png"></H2>
    <BLOCKQUOTE>
    <P>
    This command resets the interpreter, which clears the display and resets all state.
    </P>
    </BLOCKQUOTE>
    
    <H2>Keybindings</H2>
    <BLOCKQUOTE>
    <P>
    The Ghidra <I>PyGhidra Interpreter</I> supports the following hard-coded keybindings:
    <UL>
      <LI><B>(up):</B>&nbsp;&nbsp;Move backward in command stack</LI>
      <LI><B>(down):</B>&nbsp;&nbsp;Move forward in command stack</LI>
      <LI><B>TAB:</B>&nbsp;&nbsp;Show code completion window</LI>
    </UL>
    
    <P>
    With the code completion window open:
    <UL>
      <LI><B>TAB:</B>&nbsp;&nbsp;Insert currently-selected code completion (if no completion selected, select the first available)</LI>
      <LI><B>ENTER:</B>&nbsp;&nbsp;Insert selected completion (if any) and close the completion window</LI>
      <LI><B>(up):</B>&nbsp;&nbsp;Select previous code completion</LI>
      <LI><B>(down):</B>&nbsp;&nbsp;Select next code completion</LI>
      <LI><B>ESC:</B>&nbsp;&nbsp;Hide code completion window</LI>
    </UL>
    </P>
    </BLOCKQUOTE>
    
    <H2>Copy/Paste</H2>
    <BLOCKQUOTE>
    <P>
    Copy and paste from within the Ghidra <I>PyGhidra Interpreter</I> should work as expected for 
    your given environment:
    <UL>
      <LI><B>Windows:</B>&nbsp;&nbsp;CTRL+C / CTRL+V</LI>
      <LI><B>Linux:</B>&nbsp;&nbsp;CTRL+C / CTRL+V</LI>
      <LI><B>OS X:</B>&nbsp;&nbsp;COMMAND+C / COMMAND+V</LI>
    </UL>
    </P>
    </BLOCKQUOTE>
    
    <H2>API Documentation</H2> 
    <BLOCKQUOTE>
    <P>
    The built-in <TT>help()</TT> Python function has been altered by the Ghidra <I>PyGhidra Interpreter</I>
    to add support for displaying Ghidra's Javadoc (where available) for a given Ghidra class, method, 
    or variable.  For example, to see Ghidra's Javadoc on the <TT>state</TT> variable, simply do:
    <PRE> 
    >>> help(state)
    #####################################################
    class ghidra.app.script.GhidraState
      extends java.lang.Object

     Represents the current state of a Ghidra tool

    #####################################################

    PluginTool getTool()
       Returns the current tool.

      @return ghidra.framework.plugintool.PluginTool: the current tool

    -----------------------------------------------------
     Project getProject()
       Returns the current project.

       @return ghidra.framework.model.Project: the current project

    -----------------------------------------------------
    ...
    ...
    ...
    </PRE>
    <P>
    Calling help() with no arguments will show the Javadoc for the GhidraScript class.
    </P>
    </BLOCKQUOTE>
    
    <H2>Additional Help</H2>
    <BLOCKQUOTE>
    <P>
    For more information on the Jpype environment, such as how to interact with Java objects 
    through a Python interface, please refer to Jpype's documentation which can be found on the 
    Internet at <I><B>jpype.readthedocs.io</B></I>
    </P>
    </BLOCKQUOTE>

    <P align="left" class="providedbyplugin">Provided by: <I>PyGhidraPlugin</I></P>

	 <P>&nbsp;</P>
    <BR>
     <BR>
     <BR>

  </BODY>
</HTML>
